home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 4 / Amiga Tools 4.iso / tools / internet-tools / connect-line / cl / developer / rexx / clrexx-module.dok next >
Encoding:
Text File  |  1996-02-08  |  5.4 KB  |  136 lines
  1. Programmierrichtlinien für clrexx-Module, Rev. 01
  2. =================================================
  3.  © 1996 Ralf Ramge
  4.  
  5.  
  6. Die clrexx-Module sind ARexx-Skripte, welchen den ARexx-Programmierern  die
  7. Möglichkeit bieten, darin enthaltene Routinen ähnlich Library-Funktionen in
  8. eigenen Skripten zu nutzen.
  9.  
  10. Um eine einheitliche Verwendungsweise der clrexx-Module zu ermöglichen  und
  11. Kompatibilitätsprobleme  zu  vermeiden, sind clrexx-Module entsprechend den
  12. Angaben dieses Dokuments zu programmieren bzw. zu benutzen.
  13.  
  14. 1. Allgemeines
  15. --------------
  16.  
  17. Die   clrexx-Module   befinden    sich    stets    in    dem    Verzeichnis
  18. CONNECTLINE:Rexx/Modules  und  sind an dem Suffix .clrexxmod des Filenamens
  19. erkennbar. Die Benutzung durch eigene ARexx-Skripte bzw.  Batches  ist  auf
  20. folgende Methoden möglich:
  21.  
  22.     - synchroner Aufruf
  23.  
  24.       rx <clrexx-Modul> <Funktion> [<Parameterliste>]
  25.  
  26.       Bei diesem Aufruf wartet das eigene Skript auf das Ende der Bearbei-
  27.       tung und sämtliche Ein- und Ausgaben des clrexx-Modules erfolgen im
  28.       aktuellen Fenster. Fehlermeldungen des clrexx-Moduls erfolgen mit-
  29.       tels Returncodes.
  30.  
  31.     - asynchroner Aufruf 1
  32.  
  33.       run >NIL: rx <clrexx-Modul> <Funktion> [<Parameterliste>]
  34.  
  35.       Das eigene Skript wartet mit der Abarbeitung nicht auf das clrexx-
  36.       Modul, es erfolgen keine Ausgaben des Moduls.
  37.  
  38.     - asynchroner Aufruf 2
  39.  
  40.       run ><Datei>: rx <clrexx-Modul> <Funktion> [<Parameterliste>]
  41.  
  42.       Das eigene Skript wartet mit der Abarbeitung nicht auf das clrexx-
  43.       Modul, Ausgaben des Moduls erfolgen in einer temporären Datei.
  44.       Diese Datei ist vom eigenen Skript nach ihrer Benutzung zu lösch-
  45.       en.
  46.  
  47.     - asynchroner Aufruf 3
  48.  
  49.       run rx <clrexx-Modul> <Funktion> [<Parameterliste>]
  50.  
  51.       Das eigene Skript wartet mit der Abarbeitung nicht auf das clrexx-
  52.       Modul, sämtliche Ausgaben des clrexx-Moduls erfolgen im aktuellen
  53.       Fenster.
  54.  
  55. Innerhalb der  Skripte/Batches  sollte  die  benötigte  Versionsnummer  des
  56. clrexx-Moduls angegeben, besser noch überprüft werden.
  57.  
  58.  
  59. 2. Programmierung von clrexx-Modulen
  60. ------------------------------------
  61.  
  62. 2.1 Dokumentation
  63. -----------------
  64.  
  65. Jedes clrexx-Modul muß in seinem Header einen Versionsstring enthalten,  um
  66. ein stabiles Laufen von Skripten/Batches garantieren zu können.
  67.  
  68. Die  einzelnen  Funktionen  und  die  benötigten  Übergabeparameter  werden
  69. innerhalb des Skriptes oder in einer eigenen Dokumentation genau erläutert.
  70.  
  71.  
  72. 2.2 Analyse der Parameterliste
  73. ------------------------------
  74.  
  75. Ein clrexx-Modul verarbeitet  eine  beliebig  lange  Parameterliste,  deren
  76. einzelne  Parameter  als  ein String werden. Die einzelnen Parameter können
  77. durch Leerzeichen oder Kommata getrennt sein, eine eventuelle  Wandlung  in
  78. upper-  bzw.  lowercase  ist  vom  clrexx-Modul  vorzunehmen.  Beim  ersten
  79. Parameter handelt es sich stets um den Namen der gewünschten Funktion,  die
  80. Benutzung   eventueller   weiterer   Parameter  ist  optional  und  in  den
  81. Beschreibungen der jeweiligen  Funktion  dokumentiert.  Auf  eine  korrekte
  82. Reihenfolge  der  Parameter  braucht  innerhalb  eines  clrexx-Moduls nicht
  83. geprüft zu werden.
  84.  
  85.  
  86. 2.3 Nutzung von Libraries
  87. -------------------------
  88.  
  89. Jedes clrexx-Modul muß gewährleisten, daß  die  cl_rexx.library  auf  jeden
  90. Fall  geöffnet  wurde.  War  dies nicht möglich, wird der Returncode 10 vom
  91. clrexx-Modul  zurückgegeben,  bzw.  auf  die  Nutzung  von  Funktionen  der
  92. cl_rexx.library  vollständig  verzichtet.  Benutzte  Libraries  sind  nicht
  93. wieder mittels REMLIB() freizugeben. Die Benutzung  von  anderen  Libraries
  94. als  der  cl_rexx.library  und  der  rexxsupport.library  sollte  vermieden
  95. werden.
  96.  
  97.  
  98. 2.4 STDIO innerhalb des clrexx-Moduls
  99. -------------------------------------
  100.  
  101. Die generelle Nutzung von eigenen Fenstern und Eingaben des  Benutzers  ist
  102. nur   dann   möglicht,  wenn  sie  vom  aufrufenden  Skript  mittels  eines
  103. übergebenen Parameters ausdrücklich erlaubt wurde. STDIN und STDOUT  dürfen
  104. ohne  diese  Erlaubnis nicht geschlossen werden. Bei allen Eingaben, welche
  105. von einem CL-Port  erfolgen,  muß  ein  Carriercheck  erfolgen;  wurde  der
  106. Carrier  verloren,  so  teilt das clrexx-Modul dies durch den Returncode -1
  107. mit und beendet sich umgehend selbst. Es ist  darauf  zu  achten,  daß  die
  108. Funktionen des clrexx-Moduls von einem Port aus genutzt werden können.
  109.  
  110.  
  111. 2.5 Der innere Aufbau eines clrexx-Moduls
  112. -----------------------------------------
  113.  
  114. Die einzelnen Funktionen des clrexx-Moduls sind  als  solche  auch  in  dem
  115. Modul  enthalten, riesige SELECT...OTHERWISE oder IF...THEN-Konstrukte sind
  116. nicht zulässig. Die Ansteuerung der jeweiligen Routinen erfolgt stets durch
  117. den internen ARexx-Befehl CALL().
  118.  
  119. Das Skript ist angemessen zu dokumentieren und übersichtlich zu  gestalten.
  120. Der  Name  der  jeweils  mit  CALL()  aufgerufen  Funktion  entspricht  dem
  121. Funktionsnamen im  uppercase,  welcher  vom  aufrufenden  Skript/Batch  dem
  122. clrexx-Modul  übergeben  wird,  ggf.  ohne  Leerzeichen  im Funktionsnamen.
  123. Subroutinen können beliebig eingefügt werden und sie daran  erkennbar,  daß
  124. ihre Namen ausschließlich Zeichen im lowercase enthalten.
  125.  
  126.  
  127. 2.6 Der Ablauf des clrexx-Moduls
  128. --------------------------------
  129.  
  130. Sollte  die  Funktion   des   clrexx-Moduls   rechenintensive   Operationen
  131. durchführen, so ist die gewünschte Priorität des clrexx-Moduls entsprechend
  132. eines vom aufrufenden Skript bzw. Batch übergebenen  optionalen  Parameters
  133. oder einer ENV-Variablen zu  setzen.  Ist dieser Parameter nicht vorhanden,
  134. so ist die Priorität stets 0 (Defaultwert).
  135.  
  136.